home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / grepsmc.arc / READ.ME < prev    next >
Encoding:
Text File  |  1986-11-30  |  6.0 KB  |  119 lines
  1.                 GREPSMC.LBR
  2.  
  3.     The chief content of this library is a translation of a public domain
  4. version of the Unix (TM) utility grep into Small C a la Hendrix.  This
  5. implementation allows most of the standard control constructs (if, else,
  6. while, do ... while, for, switch, goto, but not expr1 ? expr2 : expr3 ),
  7. only int and char variables plus 1 level of indirection and a single
  8. subscript (char *c; and char d[10]; are allowed, but not char **c; char *d[10];
  9. or char e[10,3];).
  10.  
  11.     Grep is a program primarily desiged for printing out lines in files
  12. matching (containing) a specified "regular expression".  A particular case of
  13. a regular expression is just a fully specified string of characters such
  14. as "#define".  Thus
  15.  
  16.         grep #define grepsmc.c
  17.  
  18. will list all lines in grepsmc.c containing "#define".  But regular
  19. expressions can specify more complicated patterns using "meta-characters"
  20. such as '^', '$', '.', '*', '+', '-', '\'  and '[...]'.  For example '^' and
  21. '$' match the beginning and the end of a line, respectively.  Hence
  22.  
  23.         grep ^#define grepsmc.c
  24.  
  25. matches "#define" only if it starts in column 1, and
  26.  
  27.         grep ^$ grepsmc.c
  28.  
  29. matches only lines that are empty.  The meta-character '.' matches any character
  30. except the end of line.  Thus "^..........$" matches only lines containing
  31. exactly 10 characters (counting blanks and tabs), and "h..d" matches strings
  32. "head", "heed", "hold", "hard", etc.  '*' matches 0 or more repetitions of the
  33. preceding character matched.  Thus "a.*e.*i.*o.*u" matches any line containing
  34. the five vowels in alphabetical order.  '+' matches 1 or more repetitions of
  35. the preceding character matched.  Thus "a.+e.+i.+o+.u" matches lines containing
  36. the five vowels in order separated by at least one character.  A bracket pair
  37. "[ ... ]" matches any of the symbols between the brackets.  Thus "[bc]a[nt]"
  38. matches any line containing "ban", "bat", "can", or "cat".  '-' can be used
  39. within brackets to indicate a range of characters.  Thus "[A-Za-z]" matches
  40. any upper or lower case letter, "[A-Za-z][A-Za-z0-9]*" matches any string
  41. starting with a letter and continuing with one or more letters or digits,
  42. e.g., any C identifier.  The meta-character '\' is used as a quoting character
  43. or escape character to specify symbols that otherwise have special meaning
  44. such as '[' or '*'.  Thus "\[ *[0-9]+ *\]" matches any single C subscript
  45. that is specified numerically, possibly surrounded with blanks (e.g., "[ 33]",
  46. "[ 4 ]", or "[7]", but not "[ i ]").
  47.  
  48.     There is a problem in CP/M (TM) in that lower case letters in the
  49. command line are translated to upper case and blanks delimit arguments.  Hence
  50. in this version I have adopted the convention that any letter in a regular
  51. expression is to be considered to be lower case unless it is immediately
  52. preceded by '\' when it is always considered uppercase.  Moreover blanks and
  53. tabs are coded as '_' and '`', respectively. Thus both "[\tt]he" and
  54. "[\TT]HE" match lines containing either "The" or "the".  And to locate all
  55. blank lines (i.e., all lines that are either empty or contain only blanks or
  56. tabs) one could use the pattern "^[_`]*$" .  To match actual '_' or '`',
  57. use '\_' or '\~'.  Note that some of the examples in the preceding paragraph
  58. need to be modified to work with the CP/M version.  Thus to match an
  59. identifier use "[\a-\za-z][\a-\za-z0-9]+" or "[\A-\ZA-Z][\A-\ZA-Z0-9]+".
  60.  
  61.                Usage of grep
  62.  
  63.     The general form of an invocation of grep is as follows ([ ... ]
  64. signifies an optional component):
  65.  
  66.     grep [ -Flags ] RegularExpression FileList [ > OutputFile ]
  67. or
  68.     grep [ -Flags ] RegularExpression [ < InputFile ] [ > OutputFile ]
  69.  
  70. where Flags is a sequence of letters from 'ncfhv', RegularExpression is a
  71. pattern as described above, FileList is a list of files to be scanned, and
  72. OutputFile is the optional file on which the output will be put.  In the
  73. second form, InputFile is a single file to be scanned. If both FileList and
  74. "> InputFile" are omitted, grep will expect its input from the keyboard,
  75. terminated by ^Z (CTRL Z).  This is a useful way to experiment with what a
  76. particular pattern matches.  If more than one file is scanned, the file name
  77. is printed with each line matched unless the f flag is used (see below).
  78.  
  79.     The meaning of the flags is as follows:
  80.  
  81.     n    print line numbers of lines matched.
  82.     f    reverse default for printing file name, i.e., print name if
  83.         only 1 file is scanned, omit if more than 1 is scanned.
  84.     v    print only lines that do not match.
  85.     c    print only the total number of lines matched (or not matched
  86.         if v is specified).
  87.     h    print help information (some additional meta-characters are
  88.         described)
  89.  
  90.                 Other Files 
  91.  
  92.     Also included are the files used to create GREP.COM (with the exception
  93. of the compiler itself).  The version of the compiler I have produces assembler
  94. code suitable for ASM.  To avoid having to reassemble the I/O and system-
  95. related functions, I have created HEX files IOLBCALL.HEX and LIBASM.HEX,
  96. together with header files, STDIOCB.H and LIBASM.H that provide EQU's for the
  97. entries in the HEX files.  IOLBCALL.HEX contains most of the standard C I/O
  98. functions (getc, getchar, fgets, putc, fopen, fclose, etc.; see STDIOCB.H for
  99. others included), as well as the run-time routines needed by the compiled
  100. code.  LIBASM.HEX contains printf and fprintf (recognize %c, %s, %d, %x) and
  101. supporting routines.  They were compiled from a library copyrighted by Jim
  102. Hendrix,  modified so as to provide fprintf.  Also included is CATLOAD.COM,
  103. a program allowing creation of a COM file from several HEX files.  Usage is
  104.  
  105.     catload    file1.hex [file2.hex ... ] comfile.com
  106.  
  107. Catload can produce a COM file up to about 30K. With SMC.COM (the compiler),
  108. CATLOAD.COM, STDIOCB.H, LIBASM.H, IOLBCALL.HEX, and LIBASM.HEX on drive a:,
  109. the sequence I used to create GREP.COM was
  110.  
  111.     A>SMC B:GREPSMC.C > B:GREPSMC.ASM
  112.     A>ASM GREPSMC.BBZ
  113.     A>CATLOAD IOLBCALL.HEX LIBASM.HEX B:GREPSMC.HEX B:GREP.COM
  114.  
  115.                 Christopher Bingham
  116.                 792 Osceola Avenue
  117.                 St. Paul, MN 55105
  118. July 25, 1986.
  119.